Skip to content

docs(tokens): several project tokens per project, shown once - #273

Merged
gregberge merged 7 commits into
mainfrom
docs/project-tokens
Nov 16, 2026
Merged

gregberge merged 7 commits into
mainfrom
docs/project-tokens

Conversation

@gregberge

@gregberge gregberge commented Nov 5, 2026 •

Copy link
Copy Markdown
Member

Important

Merge once argos-ci/argos#2747 is deployed. It is merged (12b68f4), and the docs match its final code. Until it is deployed, they describe a UI and API that don't exist in production yet.

The CLI parts (argos project token, argos account project-token, --project on baseline download) and ARGOS_PROJECT for multi-project tokens also need argos-ci/argos-javascript#411 released. If the SDK release lags behind the deploy, hold this PR until it ships.

Documents the project tokens shipped by argos-ci/argos#2747 (Linear ARG-519). A project can have several tokens, each hashed and shown once, with permissions and an optional expiration, so the old "copy it from Settings → Authentication → Project token" and "Regenerate token" instructions are wrong.

New page: Account & access → Project tokens

  • What a token has: a name, linked projects, permissions, an expiration and a last-used date. It is shown once and can't be displayed again.
  • Where tokens are managed: in Project settings → Authentication (reviewers see the list, project admins create, rename and revoke) and in Team Settings → Tokens (team owners manage every token, including multi-project ones). Personal accounts use Settings → Tokens.
  • How to create a token, plus the Getting started Generate token button (standard permissions, 90 days), which first offers to delete the project's existing tokens.
  • Permissions: Standard (the default) and Advanced (starts with every permission ticked), the five individual permissions, and what to keep under Advanced for each use (CI uploads, reading, media, argos baseline download). Also the 403 message.
  • Expiration: 90 days by default; No expiration is discouraged and asks for confirmation. Also the expired-token error ("This project token has expired. Create a new one.").
  • Rotating without downtime: create the replacement, update the CI secret, revoke the old token once its last-used date stops moving.
  • Multi-project tokens: need ARGOS_PROJECT=owner/project; a single-project token ignores it. Transfer behavior.
  • Legacy tokens: keep every permission, never expire, and keep working. Last used shows "Never" until the next upload.
  • API: GET/POST /projects/{owner}/{project}/tokens, DELETE …/tokens/{tokenId}, and GET/POST/DELETE /accounts/{accountSlug}/project-tokens, with the role each one requires. The create endpoints require expireAt (null for never), and default permissions to every permission. The same operations are MCP tools.

Registered in docs/SUMMARY.md and in the Account & access README.

Updated mentions

  • Quickstarts (9), migration guides (7), deployments (2): ARGOS_TOKEN now links to the new page and says to create the token in Settings → Authentication and copy it right away.
  • Run Argos in CI: the Regenerate token steps are replaced with how to create a token, rotation, and the error messages. ARGOS_PROJECT is added to the env var table.
  • CLI reference: says which permission each kind of command needs (Standard has them all). baseline download needs Read projects + Upload builds and takes --project for a multi-project token. A project token identifies its project only when it is linked to a single project. New project token list|create|revoke and account project-token list|create|revoke sections, from feat: support project tokens linked to several projects, and rotate them from the CLI argos-javascript#411. Without flags, the CLI creates a token with every permission that never expires, so the docs say to pass --expires-in.
  • Standalone media: each command lists the permission it needs, for tokens limited under Advanced.
  • AI agents (review builds, flaky tests), Security & compliance export: reading needs the Read projects permission.
  • API reference intro: where tokens are created and that they're shown once. Permissions limit what a token reaches.
  • GitHub Actions auth, GitHub integration, account management, transfer, MCP server: links to the new page, wording for several tokens, and token tools.

To check before merging

🤖 Generated with Claude Code

Projects can now have several tokens, each with a name, linked projects,
permissions, an expiration and a last-used date. Tokens are hashed and
shown only once, so the docs no longer say to copy the token from the
project settings or to regenerate it.

- Add Account & access → Project tokens: where tokens are managed and by
  whom, permission presets, expiration, rotation without downtime,
  multi-project tokens and ARGOS_PROJECT, legacy tokens, and the API/MCP
  endpoints.
- Point every "Settings → Authentication → Project token" mention to
  creating a token, and replace the Regenerate section of Run Argos in CI.
- Say which permissions the CLI read commands, baseline download and
  media commands need, and that a multi-project token needs ARGOS_PROJECT.
- Transfer: tokens linked only to the project move with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
argos-ci/argos-javascript#411 adds `argos project token` and
`argos account project-token` (list, create, revoke), and lets
`finalize`, `skip`, `deploy` and `baseline download` take `--project`
for a token linked to several projects.

- CLI reference: add both command groups, with their defaults (every
  permission, no expiration) and the roles they need; drop "baseline
  download has no --project flag"; say what --project does for a
  multi-project token.
- Project tokens: mention the CLI next to the API, and that ARGOS_PROJECT
  naming another project fails with a 401 for a single-project token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gregberge and others added 5 commits November 9, 2026 09:18
argos-ci/argos#2747 (749192a65) changed what the docs describe:

- Creating a token through the API or the CLI without `permissions`
  now grants `builds:write` and `deployments:write`, not every
  permission. The CLI examples drop the now-redundant `--permissions`.
- `expireAt` is required on the REST create endpoints (`null` for a
  token that never expires). The CLI still sends `null` by default.
- The Upload from CI preset lets CI upload builds and deployments, but
  not media, instead of covering everything CI needs.
- A token linked to a single project ignores ARGOS_PROJECT instead of
  rejecting a mismatched one with a 401.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
argos-ci/argos#2747 (c9d3f56d1) replaces the three presets with two
options: Full access, the default, and Advanced, which starts with
every permission ticked. Tokens created through the API or the CLI
without `permissions`, and the onboarding token, get every permission.

- Project tokens: rewrite the permissions section around Full access
  and Advanced, with what to keep under Advanced for each use; update
  the defaults, the onboarding token and the legacy token advice.
- Replace mentions of Upload from CI and Read only in the CI guide, the
  CLI reference, the media page and the AI agent pages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gitbook-knowledge-staging
gitbook-knowledge-staging Bot removed the request for review from jsfez November 16, 2026 11:14
@gregberge
gregberge merged commit f27fcfd into main Nov 16, 2026
4 of 5 checks passed
@gregberge
gregberge deleted the docs/project-tokens branch November 16, 2026 11:16
@gitbook-knowledge-staging
gitbook-knowledge-staging Bot restored the docs/project-tokens branch November 16, 2026 11:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant